package com.tbynet.jwp.repository.spi;

import com.tbynet.jwp.repository.dto.command.TermCreateCommand;
import com.tbynet.jwp.repository.dto.command.TermUpdateCommand;

import java.math.BigInteger;
import java.util.List;

/**
 * 分类项命令仓储接口
 * 对应WordPress的术语（分类项）管理功能，包括创建、更新、删除等操作
 *
 * @author 佰亿互联
 * @version 1.0
 * @since 2025-11-04
 */
public interface _TermCommandRepository {

    /**
     * 创建分类项
     * 对应WordPress：wp_insert_term函数
     *
     * @param command 创建分类项命令
     * @return 创建的分类项ID
     */
    BigInteger createTerm(TermCreateCommand command);

    /**
     * 更新分类项
     * 对应WordPress：wp_update_term函数
     *
     * @param command 更新分类项命令
     * @return 是否更新成功
     */
    boolean updateTerm(TermUpdateCommand command);

    /**
     * 删除分类项
     * 对应WordPress：wp_delete_term函数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 是否删除成功
     */
    boolean deleteTerm(BigInteger termId, String taxonomy);

    /**
     * 批量删除分类项
     * 对应WordPress：wp_delete_term函数（批量操作）
     *
     * @param termIds 分类项ID列表
     * @param taxonomy 分类法类型
     * @return 成功删除的数量
     */
    Integer batchDeleteTerms(List<BigInteger> termIds, String taxonomy);

    /**
     * 设置分类项元数据
     * 对应WordPress：update_term_meta函数
     *
     * @param termId 分类项ID
     * @param metaKey 元数据键
     * @param metaValue 元数据值
     * @return 是否设置成功
     */
    boolean setTermMeta(BigInteger termId, String metaKey, Object metaValue);

    /**
     * 删除分类项元数据
     * 对应WordPress：delete_term_meta函数
     *
     * @param termId 分类项ID
     * @param metaKey 元数据键
     * @return 是否删除成功
     */
    boolean deleteTermMeta(BigInteger termId, String metaKey);

    /**
     * 更新分类项计数
     * 对应WordPress：wp_update_term_count函数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 是否更新成功
     */
    boolean updateTermCount(BigInteger termId, String taxonomy);

    /**
     * 清理空分类项
     * 对应WordPress：wp_delete_unused_terms函数
     *
     * @param taxonomy 分类法类型
     * @return 清理的数量
     */
    Integer cleanupUnusedTerms(String taxonomy);

    /**
     * 合并分类项
     * 对应WordPress：wp_merge_terms函数
     *
     * @param sourceTermId 源分类项ID
     * @param targetTermId 目标分类项ID
     * @param taxonomy 分类法类型
     * @return 是否合并成功
     */
    boolean mergeTerms(BigInteger sourceTermId, BigInteger targetTermId, String taxonomy);

    /**
     * 设置默认分类项
     * 对应WordPress：set_default_category函数
     *
     * @param taxonomy 分类法类型
     * @param termId 默认分类项ID
     * @return 是否设置成功
     */
    boolean setDefaultTerm(String taxonomy, BigInteger termId);

    /**
     * 转换分类项到不同分类法
     * 对应WordPress：wp_transform_term函数
     *
     * @param termId 分类项ID
     * @param sourceTaxonomy 源分类法
     * @param targetTaxonomy 目标分类法
     * @return 转换后的分类项ID
     */
    BigInteger transformTerm(BigInteger termId, String sourceTaxonomy, String targetTaxonomy);

    /**
     * 复制分类项
     * 对应WordPress自定义功能
     *
     * @param termId 源分类项ID
     * @param newName 新分类项名称
     * @param taxonomy 分类法类型
     * @return 新分类项ID
     */
    BigInteger duplicateTerm(BigInteger termId, String newName, String taxonomy);

    /**
     * 重置分类项计数
     * 对应WordPress：wp_update_term_count_now函数
     *
     * @param taxonomy 分类法类型
     * @return 重置的分类项数量
     */
    Integer resetTermCounts(String taxonomy);

    /**
     * 重新生成分类项别名
     * 对应WordPress：wp_unique_term_slug函数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 新的别名
     */
    String regenerateTermSlug(BigInteger termId, String taxonomy);

    /**
     * 批量更新分类项父级
     * 对应WordPress自定义功能
     *
     * @param termIds 分类项ID列表
     * @param parentId 新的父级ID
     * @param taxonomy 分类法类型
     * @return 成功更新的数量
     */
    Integer batchUpdateParent(List<BigInteger> termIds, BigInteger parentId, String taxonomy);

    /**
     * 清理分类项缓存
     * 对应WordPress：clean_term_cache函数
     *
     * @param termIds 分类项ID列表
     * @param taxonomy 分类法类型
     * @return 是否清理成功
     */
    boolean cleanTermCache(List<BigInteger> termIds, String taxonomy);

    /**
     * 复制分类项元数据
     *
     * 将源分类项的所有元数据复制到目标分类项，用于分类项复制、转换等场景
     *
     * @param sourceTermId 源分类项ID
     * @param targetTermId 目标分类项ID
     * @return Boolean 复制成功返回true，失败返回false
     *
     * @example
     * <pre>{@code
     * // 复制分类项元数据
     * Boolean success = termCommandService.copyTermMeta(sourceTermId, targetTermId);
     * if (success) {
     *     log.info("分类项元数据复制成功");
     * }
     * }</pre>
     *
     * @since WordPress 4.9
     */
    boolean copyTermMeta(BigInteger sourceTermId, BigInteger targetTermId);
}